Token refresh documentation #622

shaydewael · 2018-08-24T19:06:37Z

Summary

Refresh token documentation

Requirements (place an `x` in each `[ ]`)

I've read and understood the Contributing Guidelines and have done my best effort to follow them.
I've read and agree to the Code of Conduct.

codecov · 2018-08-24T19:10:19Z

Codecov Report

Merging #622 into master will not change coverage.
The diff coverage is n/a.

@@           Coverage Diff           @@
##           master     #622   +/-   ##
=======================================
  Coverage   92.01%   92.01%           
=======================================
  Files           7        7           
  Lines         426      426           
  Branches       78       78           
=======================================
  Hits          392      392           
  Misses         19       19           
  Partials       15       15

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 4ea73ad...52df0c6. Read the comment docs.

aoberoi · 2018-08-24T23:34:50Z

@shanedewael can you target this PR at the feat-short-lived-tokens branch, instead of master?

aoberoi · 2018-08-27T21:29:13Z

whoa i didn't even know you could do that without closing the PR and opening a new one! 🎉

aoberoi · 2018-08-27T22:12:12Z

README.md

@@ -51,6 +51,8 @@ through building your first Slack app using Node.js.
 that explains and compares the options. If you're still not sure,
 [reach out for help](#getting-help) and our community can guide you.

+**Building a workspace app?** Token rotation is required for distributed workspace apps and recommended for non-distrubted. The `WebClient` takes care of this automagically when you pass in a refresh token. Take a look at [the `WebClient` documentation](https://slackapi.github.io/node-slack-sdk/web_api#using-refresh-tokens) to see a working example.


spelling (non-distribted -> non-distributed).

but actually, i think we don't have to be that specific here, maybe:

The WebClient can automatically handle token rotation for your app. Learn more about why you should enable token expiration (hint: its required for App Directory distribution).

aoberoi · 2018-08-27T22:13:51Z

docs/_pages/getting_started.md

-a later step, you'll be asked to use this URL in your code.
+website. You have the option to build a user-token app or a workspace app. Give your app a fun name and choose a Development Slack Workspace. We recommend using a workspace where you aren't going to disrupt real work getting done -- you can create a new workspace for free.
+
+> ⚠️ For this guide, we'll assume you're building a [workspace app](https://api.slack.com/workspace-apps-preview). Workspace apps support Slack's latest-and-greatest platform features and will be required for distributed apps in the (near) future. However, most steps are the same for user-token apps.


Workspace apps support Slack's latest-and-greatest platform features and will be required for distributed apps in the (near) future.

spicy. is this true? it's likely, but i don't think we can state this for sure yet.

oops I was thinking of refresh tokens when I wrote this 😓

aoberoi · 2018-08-27T22:16:22Z

docs/_pages/getting_started.md

 of data, while others are very specific and let your app touch just a tiny sliver. Your users (and
 their IT admins) will have opinions about which data your app should access, so we recommend finding
 the scope(s) with the least amount of privilege for your app's needs. In this guide we will use the
-Web API to perform a search for messages. The scope required for this is called `search:read`. Use
-the dropdown or start typing its name to select and add the scope, then click "Save Changes".
+Web API to post a message. The scope required for this is called `chat:write` (or `chat:write:user` for user-token apps). Use the dropdown or start typing its name to select and add the scope, then click "Save Changes".

 Our app has described which scope it desires in the workspace, but a user hasn't authorized those
 scopes for the development workspace yet. Scroll up and click "Install (or Reinstall) App". You'll


Install (or Reinstall) App -> Install App

aoberoi · 2018-08-27T22:30:26Z

docs/_pages/getting_started.md

 of data, while others are very specific and let your app touch just a tiny sliver. Your users (and
 their IT admins) will have opinions about which data your app should access, so we recommend finding
 the scope(s) with the least amount of privilege for your app's needs. In this guide we will use the
-Web API to perform a search for messages. The scope required for this is called `search:read`. Use
-the dropdown or start typing its name to select and add the scope, then click "Save Changes".
+Web API to post a message. The scope required for this is called `chat:write` (or `chat:write:user` for user-token apps). Use the dropdown or start typing its name to select and add the scope, then click "Save Changes".

 Our app has described which scope it desires in the workspace, but a user hasn't authorized those
 scopes for the development workspace yet. Scroll up and click "Install (or Reinstall) App". You'll
 be back at the page asking you for permission, but this time with an additional entry corresponding


be taken to your app installation page. This page is asking you for permission to install the app in your development workspace with specific capabilities. That's right, the development workspace is like every other workspace -- apps must be authorized by a user each time it asks for more permissions. Go ahead and click "Continue". The next page asks you for which conversations the app should have access to create messages within. In this case, choose "No channels", which still allows the app to directly message users who install the App -- which means you.

Resume from "When you..."

aoberoi · 2018-08-27T22:31:44Z

docs/_pages/getting_started.md


 ```shell
-$ export SLACK_WEBHOOK_URL=https://hooks.slack.com/services/...
+$ export SLACK_ACCESS_TOKEN=xoxa-...
 ```

 Open `tutorial.js` and add the following code:


Create a file called tutorial.js and add the following code:

aoberoi · 2018-08-27T22:58:25Z

docs/_pages/web_client.md

@@ -220,6 +221,128 @@ web.channels.list((err, res) => {

 ---

+### Using refresh tokens
+
+If you're using workspace apps, refresh tokens can be used to obtain short-lived access tokens that power your Web API calls from the `WebClient` (this is *required* for distributed apps). To enable the `WebClient` to automatically refresh and swap your access tokens, you need to pass your app's refresh token, client ID, and client secret in the `WebClientOptions`. 


Maybe right after the first sentence: "This can increase the security of your app, since in the event of a token accidentally being exposed, that token cannot be used against your app or your users after a short time."

aoberoi · 2018-08-27T22:59:17Z

docs/_pages/web_client.md

+
+If you're using workspace apps, refresh tokens can be used to obtain short-lived access tokens that power your Web API calls from the `WebClient` (this is *required* for distributed apps). To enable the `WebClient` to automatically refresh and swap your access tokens, you need to pass your app's refresh token, client ID, and client secret in the `WebClientOptions`. 
+
+At the time of refresh, the `WebClient` will emit a `token_refreshed` event that will contain the new access token (`access_token`) and time to expiration (`expires_in`). It's recommended to listen to this event and store the access token in a database so you have access to your active token.


the event also contains team_id and enterprise_id.

aoberoi · 2018-08-27T23:15:04Z

docs/_pages/web_client.md

+const secret = process.env.SLACK_CLIENT_SECRET;
+
+// Intialize a data structure to store team access token info (typically stored in a database)
+const slackAccessTokens = {};


i've got multiple suggestions here but i think it would be easier to talk about in person.

aoberoi · 2018-08-27T23:15:49Z

docs/_pages/web_client.md

+
+Note: Before implementing it on your own, it's suggested you read through the [token rotation documentation](http://api.slack.com/docs/rotating-and-refreshing-credentials).
+
+If you need more control over token refreshing, you don't need to pass in your refresh token, client ID, or client secret. However, you'll need to listen for `invalid_auth` errors and handle calls to `oauth.access` to fetch new access tokens:


~~handle~~ make calls

aoberoi · 2018-08-27T23:17:27Z

docs/_pages/web_client.md

+    .then(console.log)
+    .catch((error) => {
+      if (error.code === ErrorCode.PlatformError && error.data.error === 'invalid_auth') {
+        return refreshToken()


maybe a comment here to say "this error could have occurred because of an expired token, refresh and try again"

codecov · 2018-08-28T16:32:21Z

Codecov Report

Merging #622 into feat-short-lived-tokens will not change coverage.
The diff coverage is n/a.

@@                   Coverage Diff                    @@
##           feat-short-lived-tokens     #622   +/-   ##
========================================================
  Coverage                    92.01%   92.01%           
========================================================
  Files                            7        7           
  Lines                          426      426           
  Branches                        78       78           
========================================================
  Hits                           392      392           
  Misses                          19       19           
  Partials                        15       15

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 4ea73ad...c9c13dc. Read the comment docs.

aoberoi · 2018-08-28T20:55:10Z

docs/_pages/getting_started.md

-return to the OAuth & Permissions page copy the OAuth Access Token (it should begin with `xoxa`). Treat this value like a password and keep it safe. The Web API uses tokens to to authenticate the requests your app makes. In a later step, you'll be asked to use this token in your code.
+Our app has described which scope it desires in the workspace, but a user hasn't authorized those scopes for the development workspace yet. Scroll up and click "Install App". You'll be taken to your app installation page. This page is asking you for permission to install the app in your development workspace with specific capabilities. That's right, the development workspace is like every other workspace -- apps must be authorized by a user each time it asks for more permissions. 
+
+Go ahead and click "Continue". The next page asks you which conversations the app should be able to post messages in. In this case, choose "No channels", which still allows the app to directly message who install the App -- which means you. 


directly message users who install the App

aoberoi · 2018-08-28T20:57:36Z

docs/_pages/getting_started.md

@@ -141,82 +147,6 @@ ideas about where to look next:



line above still references a dev instance in the URL, change that.

aoberoi · 2018-08-28T20:59:51Z

docs/_pages/web_client.md

@@ -231,32 +231,69 @@ At the time of refresh, the `WebClient` will emit a `token_refreshed` event that
 const { WebClient } = require('@slack/client');

 const refreshToken = process.env.SLACK_REFRESH_TOKEN;


example is great!

Shane DeWael and others added 8 commits August 22, 2018 16:32

Basic token refresh example

c8ae5a0

Update basic example

9b41dc8

Start manual refresh

03b6174

Add manual refresh example and update README

1344666

Update nav

4136a7d

Wrong link

57cfe6f

remove package lock

2195338

Merge branch 'master' into token_refresh_documentation

ff5f25b

Shane DeWael added 3 commits August 24, 2018 14:26

Update Getting Started guide

32ae2a9

Small updates

b0ef1fe

oopsies

52df0c6

shaydewael changed the base branch from master to feat-short-lived-tokens August 24, 2018 23:54

aoberoi suggested changes Aug 27, 2018

View reviewed changes

Ankur docs updates

48952de

Update docs example

35c6fc6

aoberoi suggested changes Aug 28, 2018

View reviewed changes

aoberoi reviewed Aug 28, 2018

View reviewed changes

Shane DeWael added 2 commits August 28, 2018 14:01

docs link

610987f

wording change

c9c13dc

aoberoi approved these changes Aug 28, 2018

View reviewed changes

shaydewael merged commit ed5ac1f into slackapi:feat-short-lived-tokens Aug 30, 2018

shaydewael deleted the token_refresh_documentation branch August 30, 2018 01:10

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Token refresh documentation #622

Token refresh documentation #622

shaydewael commented Aug 24, 2018

codecov bot commented Aug 24, 2018 •

edited

aoberoi commented Aug 24, 2018

aoberoi commented Aug 27, 2018

aoberoi Aug 27, 2018

aoberoi Aug 27, 2018

shaydewael Aug 28, 2018

aoberoi Aug 27, 2018

aoberoi Aug 27, 2018

aoberoi Aug 27, 2018

aoberoi Aug 27, 2018

aoberoi Aug 27, 2018

aoberoi Aug 27, 2018

aoberoi Aug 27, 2018

aoberoi Aug 27, 2018

codecov bot commented Aug 28, 2018 •

edited

aoberoi Aug 28, 2018

aoberoi Aug 28, 2018

aoberoi Aug 28, 2018


		If you're using workspace apps, refresh tokens can be used to obtain short-lived access tokens that power your Web API calls from the `WebClient` (this is required for distributed apps). To enable the `WebClient` to automatically refresh and swap your access tokens, you need to pass your app's refresh token, client ID, and client secret in the `WebClientOptions`.

		At the time of refresh, the `WebClient` will emit a `token_refreshed` event that will contain the new access token (`access_token`) and time to expiration (`expires_in`). It's recommended to listen to this event and store the access token in a database so you have access to your active token.


		Note: Before implementing it on your own, it's suggested you read through the [token rotation documentation](http://api.slack.com/docs/rotating-and-refreshing-credentials).

		If you need more control over token refreshing, you don't need to pass in your refresh token, client ID, or client secret. However, you'll need to listen for `invalid_auth` errors and handle calls to `oauth.access` to fetch new access tokens:

		@@ -231,32 +231,69 @@ At the time of refresh, the `WebClient` will emit a `token_refreshed` event that
		const { WebClient } = require('@slack/client');

		const refreshToken = process.env.SLACK_REFRESH_TOKEN;

Token refresh documentation #622

Token refresh documentation #622

Conversation

shaydewael commented Aug 24, 2018

Summary

Requirements (place an x in each [ ])

codecov bot commented Aug 24, 2018 • edited

Codecov Report

aoberoi commented Aug 24, 2018

aoberoi commented Aug 27, 2018

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

codecov bot commented Aug 28, 2018 • edited

Codecov Report

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Requirements (place an `x` in each `[ ]`)

codecov bot commented Aug 24, 2018 •

edited

codecov bot commented Aug 28, 2018 •

edited